home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 May: Tool Chest / Developer CD Series Tool Chest (Apple Computer)(May 1999).iso / Tool Chest / Development Kits / MPW etc / Miscellaneous / MPW p2c / p2cLibraries / PHeap.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-29  |  6.3 KB  |  152 lines  |  [TEXT/MPS ]
  1. /*---------------------------------------------------------------------------*
  2.  |                                                                           |
  3.  |            <<< PHeap.h - Heap Manager Routines Header File >>>            |
  4.  |                                                                           |
  5.  *---------------------------------------------------------------------------*/
  6.  
  7.  
  8. #ifndef __PHEAP__
  9. #define __PHEAP__
  10.  
  11. #ifndef __TYPES__
  12. #include <Types.h>
  13. #endif
  14.  
  15. /*
  16.  NOTE: PLEASE READ THE FOLLOWING BEFORE USING THIS HEADER FILE:
  17.  
  18.  It is assumed that by including Heap.h in your program, your memory management
  19.  consists only of allocations, and deallocations of all allocations beyond a
  20.  specified point.  In other words your memory management assumes a Pascal-like
  21.  heap management that allows new, mark, and release.  That is precisely what
  22.  the Heap Manager provides!
  23.  
  24.  The Heap Manager is an efficient memory allocation scheme that only assumes
  25.  allocations with new, remembering a location with mark, and releasing memory
  26.  back to the "mark" with release.  It can be more efficient than the more
  27.  general malloc and free because of the simple memory model imposed by this
  28.  form of allocation.  A malloc/free model (or in Pascal new/dispose) requires
  29.  more overhead per allocation and more code to maintain allocated and freed
  30.  blocks.  Note, however, use of the Heap Manager does NOT preclude use of
  31.  malloc and free.  Both memory models may coexist simultaneously without
  32.  conflict (other than possible fragmentation due to differences in the sizes
  33.  of the underlying memory allocations utilized by each of the model's
  34.  algorithms).                                                                                                                                    */
  35.  
  36. /* This file contains:
  37.  
  38. initHeap(size, delta, nonCont, proc)    - Heap Manager inititialization
  39. New(amount)                                                        - Allocate amount space on the heap
  40. Mark(p)                                                                - Set p to point at current heap position
  41. Release(p)                                                        - Free heap space back to p
  42.  
  43. */
  44.  
  45. #ifdef __cplusplus
  46. extern "C" {
  47. #endif
  48.  
  49.  
  50. extern OSErr initHeap(long initSize, long delta, Boolean nonCont, 
  51.                                             void (*errProc)());
  52.     /*
  53.     Call this proc to initialize the Heap Manager.  The parameters detemine
  54.     certain characteristics of the way the heap is allocated.
  55.     
  56.     The initSize parameter determines the initial size (in bytes) of the
  57.     unallocated heap.  When this space if fully allocated an attempt is made to
  58.     extend this space contiguously with the original space.  If that extension is
  59.     unsuccessful, and the parameter nonCont is set to true, a new "chunk" of
  60.     (generally, non-contiguous) heap space is allocated.  The size of this
  61.     additional heap space is specified by the delta parameter (again the size is
  62.     in bytes).
  63.     
  64.     If anything goes wrong during allocation of the heap or space within it, for
  65.     example, additional contiguous space cannot be allocated and nonCont was set
  66.     false, then the Heap Manager uses the errProc to report the error to the
  67.     caller.  The errProc call can be done from initHeap, new, or release, and they
  68.     assume the following declaration:
  69.  
  70.     void errProc(heapResult)
  71.         OSErr heapResult;
  72.     {
  73.         - - -
  74.     }
  75.     
  76.     The heapResult is an error number appropriate to the situation usually
  77.     reported by the underlying system memory management routines (the routines the
  78.     Heap Manager itself uses).  The errProc may or may not return to the Heap
  79.     Manager.  If it does, error reporting from the individual Heap Manager
  80.     routines is the same as if no errProc was supplied which is the case we will
  81.     describe shortly.  Either way, the heapResult code of the most recent Heap
  82.     Manager call is available in the global heapResult:                                                    */
  83.     
  84.     extern OSErr heapResult;                        /* Most recent heap error result code        */
  85.                                                                                                                                                             /*
  86.     If there is no errProc, i.e., NULL is specified, or, as we just said, the
  87.     errProc returns, then error reporting is a function of each routine and is
  88.     discussed with the description of that routine.  In the case of initHeap,
  89.     an error code (the same one passed to the errProc) is returned as the
  90.     function result, or 0 if there is no error.
  91.  
  92.   The only error that could result from calling initHeap is a failure to
  93.     allocate the initial heap of initSize bytes.  It is assumed initHeap is called
  94.     only once, and at the beginning of execution.  Thus, generally you don't have
  95.     to check the return code because, if the initial allocation fails, something
  96.     is seriously wrong with your system, and something else is also bound to fail
  97.     that you will check!
  98.     
  99.     If initHeap is NOT called, then it will be automatically called on the first
  100.     call to new.  The call will be done as,
  101.     
  102.     initHeap(initalHeap, heapDelta, nonContiguous, memErrProc);
  103.     
  104.     (and, by the way, the return code IS checked by new -- new has its own way of
  105.     reporting errors to its caller).  The parameters are global variables that
  106.     YOU may set, i.e.,                                                                                                                    */
  107.  
  108.     extern long initalHeap;                            /* Size of initial heap chunk                        */
  109.     extern long heapDelta;                            /* Size of additional heap chunks                */
  110.     extern Boolean nonContiguous;                /* true ==> allow non-contiguous chunks    */
  111.     extern void (*memErrProc)();                /* Ptr to memory error proc                            */
  112.                                                                                                                                                             /*
  113.     Thus you may bypass the explicit initHeap, letting new do it, with values
  114.     that you can set.  If you don't set them then they are defaulted to give
  115.     an initHeap call of initHeap(10000, 10000, true, NULL);
  116.     */
  117.  
  118.  
  119. extern char *New(long amount);
  120.     /*
  121.     Allocate amount bytes of heap space.  The amount is rounded up to an even
  122.     value if necessary.  If the space cannot be allocated NULL is returned (over
  123.     and above any error reporting done by the errProc specified to initHeap).
  124.     
  125.     The initHeap routine is called on the first call to new if initHeap was not
  126.     explicitly called prior to calling new.
  127.     */
  128.  
  129.  
  130. extern void *Mark(void **p);
  131.     /*
  132.     Set a pointer to the heap area.  The current "top" of heap is returned in the
  133.     parameter p and as the function result.  A subsequent call to release will
  134.     free all heap space from this point, p, on.
  135.     */
  136.  
  137.  
  138. extern void Release(void *p);    
  139.     /*
  140.     Deallocate all heap space back to the specified "mark", p.  It is assumed p
  141.     is a value set by a mark call.  All space from allocated after that mark call
  142.     is deallocated.  Pointers to that area should NOT be used again!  Errors are
  143.     not explicitly reported from a call to this proc except perhaps through the
  144.     errProc specified to initHeap.
  145.     */
  146.  
  147.  
  148. #ifdef __cplusplus
  149. }
  150. #endif
  151.  
  152. #endif